home *** CD-ROM | disk | FTP | other *** search
/ Workbench Design / WB Collection.iso / workbench werkzeuge / memory & system tools / vmm / contrib / vmminformer1_1 / docs / vmminformer.guide (.txt) next >
Amigaguide Document  |  1996-04-07  |  17KB  |  348 lines
  1. @database doc/VMMInformer.guide
  2. @$VER: VMMInformer.guide V1.1 (29.08.95)
  3. @author Torsten Ebeling
  4. @Width 72
  5. @Node Main "doc/VMMInformer.guide"
  6. @Next "COPYRIGHT"
  7.                              VMMInformer
  8.            (Graphical statistics program for use with VMM)
  9.                              User's Guide
  10.                              Version 1.1
  11.                      $Date:  95/08/29 20:41:56 $
  12.                       written by Torsten Ebeling
  13.                 email:  t_ebelin@informatik.uni-kl.de
  14. CONTENTS
  15.   0.  @{" Copyright & Author        " Link "COPYRIGHT"}
  16.   1.  @{" Introduction              " Link "INTRODUCTION"}  
  17.   2.  @{" Installation              " Link "INSTALLATION"}
  18.   3.  @{" VMMInformer               " Link "VMMInformer"}
  19.   4.  @{" Preferences file - Syntax " Link "PREFS_SYNTAX"}
  20.   5.  @{" Error list                " Link "ERROR_LIST"}
  21.   6.  @{" Known bugs                " Link "KNOWN_BUGS"}
  22.   7.  @{" History                   " Link "HISTORY"}
  23.   8.  @{" Future plans              " Link "PLANS"}
  24.   9.  @{" Acknowledgments           " Link "ACKNOWLEDGMENTS"}
  25. @EndNode
  26. @Node "COPYRIGHT" "doc/NerveEX.guide/COPYRIGHT"
  27. @Next "INTRODUCTION"
  28. @Prev "Main"
  29. @Toc "Main"
  30. @{b}0. COPYRIGHT and AUTHOR@{ub}
  31.  IMPORTANT NOTICE:  This program is copyrighted by Torsten Ebeling, but
  32.  can be freely  distributed,  provided  that  the  following  rules are
  33.  respected.
  34.  - No change is made to the program nor to the accompanying documentation
  35.  - The  package  is always distributed in its complete form.
  36.  - Every  form  of distribution is allowed and encouraged, but no fee can
  37.    be charged for this program except for, possibly, the cost of magnetic
  38.    media and/or disk duplication and shipping.
  39.  - Inclusion  in  PD  software  libraries  such as Fish Disks is allowed,
  40.    provided  the  fees  charged for these disks are comparable with those
  41.    charged by Fred Fish.
  42.  - The  program  cannot  be distributed in any commercial product without
  43.    the written consent of the author.
  44.  - The author cannot be held liable for the suitability or accuracy of or
  45.    any damage directly or indirectly caused by the use  or misuse of this
  46.    program. It is the sole responsibility of the user her/him self.
  47.  By  copying,  distributing  and/or  using  the program you indicate your
  48.  acceptance of the above rules.
  49. Author:
  50.   email:      t_ebelin@informatik.uni-kl.de
  51.   snail-mail: Torsten Ebeling
  52.               Kottenschanze 8
  53.               67659 Kaiserslautern
  54.               Germany 
  55. @EndNode
  56. @Node "INTRODUCTION" "doc/VMMInformer.guide/INTRODUCTION"
  57. @Next "INSTALLATION"
  58. @Prev "COPYRIGHT"
  59. @Toc "Main"
  60. @{b}1. INTRODUCTION@{ub}
  61. I'm  really  fed  up  with  writing manuals.  This manual will be very
  62. short.   VMMInformer is a utility which displays information about VMM
  63. or the memory situation either as text or graphic. That's it.
  64. VMMInformer requires VMM 2.1 or greater to be installed and running on
  65. your  system  if you want to display information about VMM.  Otherwise
  66. it  only  shows  'VMM  not  dependent'  information.  VMM is a virtual
  67. memory manager written by Martin Apel.  VMM is available on AMINET and
  68. several PD/Shareware Disks or CDs.
  69. @EndNode
  70. @Node "INSTALLATION" "doc/VMMInformer.guide/INSTALLATION"
  71. @Next "VMMINFORMER"
  72. @Prev "INTRODUCTION"
  73. @Toc "Main"
  74. @{b}2. INSTALLATION@{ub}
  75. VMMInformer  requires  at  least  OS2.04  to  run.   VMMInformer  also
  76. requires  VMM  2.1  or  greater to be installed to use all features of
  77. VMMInformer.
  78. Execute the following steps to install VMMInformer:
  79. - Copy @{"VMMInformer" Link "VMMINFORMER"} to your preferred path for utilities.
  80. - Copy VMMInformer.prefs to ENVARC: or generate your own preferences file.
  81. Now change the preferences file at will.
  82. I  added  three example preferences files to this archive in the prefs
  83. directory.   Use  these  preferences  files  to get a first impression
  84. about the possibilities of VMMInformer.
  85. VMMInformer  tries  to  read  the  file  specified  as argument in the
  86. command line first.  If you didn't specify a prefs-file it will try to
  87. read ENV:VMMInformer.prefs and after that ENVARC:VMMInformer.prefs.
  88. See @{"Prefs-File syntax" Link "PREFS_SYNTAX"} for more details on that.
  89. @EndNode
  90. @Node "VMMINFORMER" "doc/VMMInformer.guide/VMMINFORMER"
  91. @Next "PREFS_SYNTAX"
  92. @Prev "INSTALLATION"
  93. @Toc "Main"
  94. @{b}3. VMMINFORMER@{ub}
  95. There is not much to explain about VMMInformer:
  96.    TEMPLATE: VMMInformer [prefs-file]
  97. The  VMMInformer display shows the strings with the selected variables
  98. mixed  with  the  graphical display.  If you have defined any graphics
  99. you  can  change  the  size  of  the  window  with  the sizing-gadget,
  100. otherwise there is no sizing-gadget visible.
  101. See @{"Prefs-File syntax" Link "PREFS_SYNTAX"} for more details on that.
  102. @EndNode
  103. @Node "PREFS_SYNTAX" "doc/VMMInformer.guide/PREFS_SYNTAX"
  104. @Next "ERROR_LIST"
  105. @Prev "VMMINFORMER"
  106. @Toc "Main"
  107. @{b}4. PREFERENCES FILE - SYNTAX@{ub}
  108. @{b}IMPORTANT: DON'T@{ub} edit the first line in the preferences file.
  109. @{b}IMPORTANT:@{ub} The declaration blocks @{b}must@{ub} be defined in the following
  110.            order: 1. "TASK/WINDOW/DEFAULT"
  111.                   2. "VARIABLES"
  112.                   3. "DISPLAY"
  113. @{b}IMPORTANT:@{ub} The syntax of the preferences file will be checked
  114.            but not all errors will be recognized by the parser.
  115. @{b}Description of the preferences file syntax.@{ub}
  116. If  you  are  not able to follow my descriptions please take a look at
  117. the  example  preferences  files.  Expecially "VMMInformer.crazy" will
  118. help  you  understanding  the  preferences  file  syntax.  If you have
  119. problems with a special idea feel free to contact me and i try to help
  120. "//" starts a comment line
  121. <BYTE>     : 
  122. <UBYTE>    :
  123. <UWORD>    :
  124. <ULONG>    :
  125. <BOOLEAN>  : "TRUE" oder "FALSE"
  126. <STRING>   : Must be enclosed by quotes. I.e.: "test test test"
  127.              The  string  must  be  entered in printf-style format.  A
  128.              maximum of 6 variables is allowed. In normal text strings
  129.              only one variable is allowed.
  130. <VAR>      : One of the variables defined below (except d).
  131. <FUNCTION> : For the definition of functions you must use @{b}RPN-format@{ub}.
  132.              You can use the following variables for your calculations:
  133.             a) Variables defined in the VMStat-structure:
  134.                - VMSize         : Size of virtual memory 
  135.                - VMFree         : Size of free virtual memory
  136.                - Faults         : Page faults up until now
  137.                - PagesWritten   : Pages written up until now
  138.                - PagesRead      : Pages read up until now
  139.                - NumFrames      : Actual no. of used frames
  140.                - PagesUsed      : Pages used on device
  141.                - PageSize       : Pagesize
  142.                - TrapStructsFree: No. of free TrapStructs
  143.                See "VMM.guide" for more details.
  144.             b) 4 more variables concerning free memory and the time:
  145.                - PUBLIC_FAST_Free: Free PUBLIC FAST memory
  146.                - CHIP_Free       : Free CHIP memory
  147.                - CurrentSeconds  : Current time (seconds)
  148.                - CurrentMicros   : Current time (micros)
  149.             c) All key variables:
  150.                Only SECONDS and MICROS may be of interest. (see below)
  151.             d) Constants: i.e. 1, 45, 100000, ...  (no negative values)
  152.             e) All "ARRAY"-variables defined.
  153.             f) All variables defined with "DEFINE" (functions).
  154.                IMPORTANT: variables in e) and f) @{ub}must@{b} be defined
  155.                           before they are used!!!
  156.             @{b}SYNTAX of functions:@{ub}
  157.             IMPORTANT: Only    ULONG    variables    are    used   for
  158.                        calculations.   In  complex  calculations round
  159.                        off  errors  can occur.  This doesn't mean your
  160.                        processor   is  faulty  (INTEL  outside).   ALL
  161.                        variables are stored as ULONG integers.
  162.             All functions MUST be entered in @{b}RPN-format@{ub}!
  163.             The following operators are allowed: +, -, *, /, %
  164.             Examples:
  165.               i)   Size of free virtual memory:
  166.                    - DEFINE VMUsed = VMSize VMFree -
  167.               ii)  No. of pagefaults during an update cycle:
  168.                    - ARRAYFaults = Faults
  169.                    - DEFINE Faults_per_update = ARRAYFaults(0) ARRAYFaults(-1) -
  170.               iii) No. of faults during 1 second:
  171.                    - SECONDS = 20
  172.                    - MICROS  = 500000
  173.                    - ARRAYFaults = Faults
  174.                    - DEFINE Update_Micros = SECONDS 1000000 * MICROS +
  175.                    - DEFINE Faults_per_update = ARRAYFaults(-1) ARRAYFaults(0) -
  176.                    - DEFINE Faults_per_second = Faults_per_update 1000000 * Update_Micros /
  177. --> START OF PREFERENCES FILE
  178. **********************************************************************
  179. "BEGIN  TASK/WINDOW/DEFAULT"  starts  the  definition  of the task and
  180.                               window specific variables.
  181. "VERSION = <UBYTE>"   Version of preferences file format.   @{b}DON'T EDIT@{ub}
  182. "REVISION = <UBYTE>"  Revision of preferences file format.  @{b}DON'T EDIT@{ub}
  183. "PRIORITY = <BYTE>"  Priority of VMMInformer task (-128 bis 127).
  184. "LEFT = <UWORD>"     Left edge of window.
  185. "TOP  = <UWORD>"     Right edge of window.
  186. "WIDTH  = <UWORD>"   Width of window.
  187.                      (The height depends on the font and the
  188.                       contents of the window.)
  189. "ZOOMED = <BOOL>"        Open window zoomed (TRUE) or unzoomed (FALSE).
  190. "ZOOMED_LEFT = <UWORD>"  Left edge of the zoomed window.
  191. "ZOOMED_TOP  = <UWORD>"  Right edge of the zoomed window.
  192. "BACKFILLCOLOR = <UBYTE>"  Background color (pen no.)
  193. "PANELCOLOR    = <UBYTE>"  Panel color      (pen no.)
  194. "TEXTCOLOR     = <UBYTE>"  Text color       (pen no.)
  195. "AUTOSCALE = <BOOLEAN>" TRUE  enables autoscale option.
  196.                         FALSE disables autoscale option.
  197.                         (see "EXCEED_COLOR").
  198. "SHIFT  =  <UWORD>"  Shift the graphic <SHIFT> pixels to the left when
  199.                      the right window border is reached.
  200. "COLOR        = <UBYTE>" Default color for the graphical display. (pen no.)
  201. "EXCEED_COLOR = <UBYTE>" Color which is used to mark that the value
  202.                          exceeds the graphical display.
  203. "SECONDS = <ULONG>"
  204. "MICROS  = <ULONG>" Update the window every x seconds and y micros.
  205. "END" ends this definition.
  206. **********************************************************************
  207. "BEGIN VARIABLES" starts the declaration of the variables.
  208. "ARRAY<ident>  = <VAR>" Declaration  of  a  variable which can be used in
  209.                         calculations  later.  All values of this variable
  210.                         are stored in an array.  (Up to the actual screen
  211.                         size).   <ident>  is  the  name of this variable.
  212.                         The  name  must follow directly after the keyword
  213.                         "ARRAY".
  214.                         I. e.: "ARRAY0", "ARRAYVMFree", "ARRAYStarTrek", ...
  215.                         Alphanumeric  and numeric characters are allowed.
  216.                         You can access the last value stored in the array
  217.                         as follows:
  218.                          - ARRAY<ident>(-1)
  219.                         The  value  in  parentheses  can  be  between the
  220.                         current screen width - 1 and 0 (a negative number).
  221.       
  222. "DEFINE  <var> = <FUNCTION>" This defines a new variable which will be
  223.                              recalculated  every  update cycle.  <var>
  224.                              is  the name of this variable.  After you
  225.                              have defined this variable you can access
  226.                              it  in  the  following calculations.  You
  227.                              can't  access  a  variable  which has not
  228.                              been  defined  before  it is used for the
  229.                              first time.
  230. "END" ends this declaration.
  231. **********************************************************************
  232. "BEGIN DISPLAY" starts the definition of strings and graphics.
  233. "@{"TITLE" Link "EXAMPLE_TITLE"} = <STRING>[, <VAR>[, <VAR>]...]"     Window title
  234. "@{"ZOOMTITLE" Link "EXAMPLE_TITLE"} = <STRING>[, <VAR>[, <VAR>]...]" Window title in zoomed state.
  235. "@{"TEXT" Link "EXAMPLE_TEXT"} =  <STRING>[, <VAR>]" Strings defined in this way are displayed
  236.                              in   the   window   in   order  of  their
  237.                              definition.  <STRING> is the string to be
  238.                              displayed  in the window and <VAR> is the
  239.                              linked variable. <VAR> is optional.
  240. "@{"GRAPHIC" Link "EXAMPLE_GRAPHIC"} = <var> [, [<height>], [[<pen>], [[<autoscale>], [[<scale_factor>], [[<bars>]]]]]]"
  241.    "var"        = <VAR>     defines which variable is displayed as graphic.
  242.    "height"     = <ULONG>   overrides the default height
  243.    "pen"        = <UBYTE>   overrides the default pen number.
  244.    "autoscale"  = <BOOLEAN> overrides the default AUTOSCALE option.
  245.    "scale_size" = <ULONG>   value, in which distance the graphic is scaled
  246.    "bars"       = <BOOLEAN> enables scalebars (TRUE) or disables them (FALSE)
  247.    These variables are always only in reference to the actual defined
  248.    graphic.
  249. "BAR = <UBYTE>" color (pen no.)
  250. "END" ends this definition.
  251. **********************************************************************
  252. --> END OF PREFERENCES FILE
  253. @EndNode
  254. @Node "ERROR_LIST" "doc/VMMInformer.guide/ERROR_LIST"
  255. @Next "KNOWN_BUGS"
  256. @Prev "PREFS_SYNTAX"
  257. @Toc "Main"
  258. @{b}5. ERROR LIST@{ub}
  259. **********************************************************************
  260. Possible errors during preferences file parsing:
  261. Error no.:      Description:
  262.     1           out of memory
  263.     2           couldn't open config file
  264.     3           SYNTAX error
  265.     4           undefined identifier or use out of BEGIN ... END
  266.     5           argument missing
  267.     6           ULONG argument missing: ULONG required
  268.     7           BOOLEAN argument missing: "TRUE" or "FALSE" required
  269.     8           quote mark missing
  270.     9           invalid argument
  271.    10           DAU, total memory failure in 2 minutes ;-)
  272.    11           "ARRAY" is not a valid variable name
  273.    12           invalid use of variable
  274.    13           variable name not found
  275.    14           invalid array offset
  276.    15           no graphic defined
  277.    16           wrong version of preferences file
  278. **********************************************************************
  279. @EndNode
  280. @Node "KNOWN_BUGS" "doc/VMMInformer.guide/KNOWN_BUGS"
  281. @Next "HISTORY"
  282. @Prev "ERROR_LIST"
  283. @Toc "Main"
  284. @{b}6. KNOWN BUGS@{ub}
  285. If you find any bugs please mail them to me.
  286. If  VMM isn't able to start correctly for some reason, VMMInformer may
  287. hang.   This  is  not an error but is due to VMMInformer waiting for a
  288. response from VMM which isn't able to respond.
  289. @EndNode
  290. @Node "HISTORY" "doc/VMMInformer.guide/HISTORY"
  291. @Next "PLANS"
  292. @Prev "KNOWN_BUGS"
  293. @Toc "Main"
  294. @{b}7. HISTORY@{ub}
  295. Version 1.1 : 
  296.  - Changed the preferences file syntax
  297.    (see convert.readme for more details)
  298.  - Changed VMMInformer to work without VMM running.
  299.  - Added two new variables for use with the graphical display
  300.      a) "scale_size"
  301.      b) "bars"
  302.  - Text and graphical displays can be mixed together
  303.  - Added a color configurable bar to seperate the output
  304.  - Fixed a bug which caused VMMInformer to open the window always at
  305.    the zoomed position
  306.  - Fixed a bug which caused VMMInformer to clear the screen title while
  307.    VMMInformer window is the active one
  308.  - Minor bug fixes and changes
  309. Version 1.0 : First release
  310. @EndNode
  311. @Node "PLANS" "doc/VMMInformer.guide/PLANS"
  312. @Next "ACKNOWLEDGMENTS"
  313. @Prev "KNOWN_BUGS"
  314. @Toc "Main"
  315. @{b}8. FUTURE PLANS@{ub}
  316. - Integrate CPULoad in VMMInformer
  317. @EndNode
  318. @Node "ACKNOWLEDGMENTS" "doc/VMMInformer.guide/ACKNOWLEDGMENTS"
  319. @Prev "PLANS"
  320. @Toc "Main"
  321. @{b}9. ACKNOWLEDGMENTS@{ub}
  322. I  would  like  to  thank  Martin Apel for providing me with ideas and
  323. helping me with problems.
  324. @EndNode
  325. @Node "EXAMPLE_GRAPHIC"
  326. @Toc "Main"
  327. Example about @{b}GRAPHIC@{ub}
  328. GRAPHIC = CPULoad, 30, 5, TRUE, 10, TRUE
  329. (Overrides default height, pen color and autoscale modus.  Sets
  330.  the scale_size to 10 and enables the scale bars)
  331. GRAPHIC = CHIP_Free,, 5                (overrides default pen color)
  332. Don't forget the commas if you only want to change the second or third
  333. attribute without touching the first or second one.
  334. @EndNode
  335. @Node "EXAMPLE_TEXT"
  336. @Toc "Main"
  337. Example about @{b}TEXT@{ub}
  338. TEXT = "Chip memory free:", CHIP_Free
  339. TEXT = "Fast memory free:", PUBLIC_FAST_Free
  340. @EndNode
  341. @Node "EXAMPLE_TITLE"
  342. @Toc "Main"
  343. Example about @{b}TITLE@{ub}
  344. TITLE = "VMMInformer %1.1ld.%1.1ld", VERSION, REVISION
  345. ZOOMTITLE = "VM: %5ld K, Chip: %4ld K, Fast: %5ld K  %2.2ld:%2.2ld:%2.2ld", VMFreeK, CHIP_FreeK, PUBLIC_FAST_FreeK, Hours, Minutes, Seconds
  346. VMFreeK, CHIP_FreeK, PUBLIC_FAST_FreeK, Hours, Minutes, Seconds are user defined variables.
  347. @EndNode
  348.